The VideoToolbox is a collection of two hundred C subroutines and several demo and utility programs that I and others have written to do visual psychophysics with Macintosh computers. It is fully compatible with 680x0 and PowerPC Macs and with Metrowerks CodeWarrior 5 and Symantec THINK 7/8 C compilers. It's free and may not be sold without permission. It should be useful to anyone who wants to present accurately specified visual stimuli or use the Mac for psychometric experiments. The text file "Video synch" discusses all the ways of synchronizing programs to video displays and the many pitfalls to avoid. The TimeVideo application checks out the timing of all video devices in anticipation of their use in critical real-time applications, e.g. movies or lookup table animation. "Video bugs" reports all known bugs uncovered by TimeVideo's testing of 56 video cards and drivers. Low-level routines control video timing and lookup tables, display real-time movies, and implement the luminance-control algorithms suggested by Pelli and Zhang (1991). In particular, GetPixelsQuickly and SetPixelsQuickly peek and poke pixels in bitmaps and pixmaps, CopyBitsQuickly and CopyWindows faithfully copy between bit/pixmaps and the screen, WindowToEPS saves an image to disk as encapsulated PostScript, for later printing or incorporation into a document, and SetEntriesQuickly and GDSetEntries load the screen's color lookup table, all without any of QuickDraw's color translations. High-level routines help analyze psychophysical experiments (e.g. maximum-likelihood fitting and graphing of psychometric data). Assign.c is a runtime C interpreter for C assignment statements, which is useful for controlling experiments and sharing calibration data. This collection has been continually updated since 1991. More that one hundred colleagues subscribe to the update list (see below), and have indicated that they are using the software in their labs. Documentation is in the source files themselves. Many of the routines are Mac-specific, but some very useful routines, e.g. the luminance-control, statistics, maximum-likelihood fitting algorithms, and the runtime interpreter are written in Standard C and will work on any computer. Those wishing to acknowledge use of the VideoToolbox software might cite:
Pelli, D. G. and Zhang, L. (1991) Accurate control of contrast on microcomputer displays. Vision Research, 31, 1337-1350. Reprints are available.
AVAILABILITY:
The VideoToolbox software is updated several times a year. You can download the latest version from any of the archives below. To get future versions automatically, just send me your email address. Each time I post a new version of the VideoToolbox to the Info-Mac Archive, I email a copy to everyone on the subscription list; there are currently 151 subscribers.
CompuServe://MacDev forum/Library 4 C and Pascal/VIDEOT.SEA
(The filename changes slightly to reflect each version's release date. You can request a file from the Info-Mac Archive by email; for instructions send a query to Info-Mac-Request@sumex-aim.stanford.edu.)
[The ISR Video Attenuator is a commercial product. Ordering instructions are in the "Video attenuator" file. I have no financial involvement in the ISR Video Attenuator.]
AUTHORS:
Adobe (ATMInterface.c and ATMInterface.h)
Apple (IsCmdPeriod.c,MoveMouse.c,TrapAvailable.c, Zoom.c)
Kevin Bell (PatchExitToShell in Timer.c)
Philipp Biermann ("Multisync Sense Pins.note")
David Brainard (12 routines in Assign.c, 1 in GDOpenWindow.c, GetTimeDateString.c, PeekTimer in Timer.c)
EJ Chichilniski (SetFileInfo.c)
Raynald Comtois (SetEntriesQuickly.c)
Frans Cornelissen (VideoToolbox folder icon)
Steve Coy (PatchExitToShell in Timer.c)
Bart Farell (several routines in SetOnePixel.c and SetPixelsQuickly.c)
Bill Haake (SetEntriesQuickly.c)
Bill Hofmann (PatchExitToShell in Timer.c)
Mike Kahl (CopyQuickDrawGlobals.c, kbhit.c)
Joseph Laffey (GetVersionString.c)
Peter Lennie (SetEntriesQuickly.c)
J.N. Little & jmb (ReadMATLABFile.c)
Jamie R. McCarthy (IsCmdPeriod.c)
Izumi Ozhawa (CVNetConvert in the Utilities folder)
Denis Pelli (most of the routines)
SPLAsh Resources (HideMenuBar.c, SetMouse.c)
Dave Radcliffe (FlushCacheRange.c)
Evan Relkin (kbhit.c)
Mike Schechter (PixMapToPICT.c)
Preeti Verghese (GetVoltage.c)
Detailed attribution appears in each file. Please advise of any errors or omissions.
C COMPILERS:
If you don't have a compiler, I'd suggest buying Metrowerks CodeWarrior C Gold ($99 academic price). All the VideoToolbox demos now compile and run as native code on both 68k and Power PC Macs, using CodeWarrior C version CW5.5. If you must use THINK C, I suggest that you upgrade to version 8, but I prefer CodeWarrior. See the VideoToolbox "Advice" document for comments and ordering information.
MATLAB:
David Brainard (brainard@condor.psych.ucsb.edu) has created interface files that make it easy to use the VideoToolbox from within MATLAB. They're available by anonymous ftp. Also see VideoToolboxMATLAB.c in VideoToolboxSources.
Josh Solomon, jsolomon@vision.arc.nasa.gov, writes, "Beau Watson and I have created a Mathematica package containing functions for the display of grayscale movies on Macintosh-driven monitors. The functions load movies from files (or directly from Mathematica) to off-screen memory, calculate color maps (using a VideoToolbox-style luminance record) and display the movies. This package will be published soon."
Josh didn't say, but I expect that they'll announce availability on their home page:
You'll need to pre-compile the header: see VideoToolbox.pch (for CodeWarrior) or VideoToolbox.c (for THINK C). If you get link errors when rebuilding your re-existing project, it is likely that you'll need to add Nan.c and MacMemory.c to your project.
GETTING STARTED:
Try the demos: Sandstorm, Grating, FlickeringGrating, Filter, and TimeVideo. TimeVideo times all of your displays, telling you how quickly you can show movies and do lookup table animation. Read "Video synch" and "Advice".
The VideoToolbox applications--mostly demos--now come in four possible flavors, indicated by the extension to the file name, e.g. Sandstorm, Sandstorm.68k, Sandstorm.ppc, or Sandstorm.fat. The plain extension indicates a 68k application produced by THINK C; it should run fine on all Macs, by virtue of the 68k emulator on the PowerPC. (However, many Macs lack the 68881 floating point unit, "fpu", and the 68k emulator on the PowerPC doesn't include fpu emulation. Applications compiled to use an fpu will fail on these computers unless you install something like SoftwareFPU. See the "Advice" document.) The ".68k" extension indicates a 68k application produced by Metrowerks CodeWarrior C; it too should run on all Macs. The ".ppc" extension indicates a PowerPC application produced by Metrowerks CodeWarrior C; it will only run on PowerPC Macs. The ".fat" extension indicates a "fat binary" 68k/PowerPC application produced by Metrowerks CodeWarrior C; it will run native on all Macs. (As you may infer from the file sizes, a fat binary file is essentially the combination of the two native applications, plus a cfg resource that says what's where. Most of the "ppc" projects in the VideoToolbox collection have been configured to produce a fat application.)
You'll want the VideoToolboxSources folder to be included in your project's search path. Don't copy source files to your projects; just "Add" them using your compiler's Source or Project menu. That will make it easy to update the VideoToolbox. In Metrowerks, add the VideoToolboxSources folder to each of your projects' "Access paths" preferences. For THINK C, place an alias to the VideoToolboxSources folder inside the THINK C Aliases folder.
Follow the instructions in VideoToolbox.pch (CodeWarrior) or VideoToolbox.c (THINK C) to precompile VideoToolbox.h to recreate the precompiled header or headers that you'll need, since they must be produced by your version of the compiler. (If you're producing an external code resource for MATLAB then use VideoToolboxMATLAB.c instead.) Put all the pre-compiled headers in "VideoToolbox:VideoToolboxSources:Precompiled headers". VideoToolbox.pch, in CodeWarrior, will automatically generate the correct file name.
Here's the naming convention that I use:
"VideoToolbox.pre" = THINK C, 68k, 2-byte int, "universal" floating point (works with or without 8881 fpu).
"VideoToolbox.68k.4i.f.pre" = CodeWarrior, 68k, 4-byte int, 12-byte double for 8881.
"VideoToolbox.68k.4i.pre" = CodeWarrior, 68k, 4-byte int, 10-byte double for no fpu.
"VideoToolbox.ppc.pre" = CodeWarrior, PowerPC, necessarily 4-byte int and 8-byte double.
Require.c: All the compilers consider it the user's responsibility (why?) to ensure that the current compiler settings are consistent with those of the object code libraries (e.g. "ANSI" in THINK C or "ANSI (4i/f) C.68k" in CodeWarrior) and the pre-compiled header. It is very easy to forget this rule, leading to mysterious crashes. (CW5 now checks for consistency of the pre-compiled header, but still doesn't check the libraries.) Therefore it is highly recommended that you call the VideoToolbox Require() once at the beginning of your program because it explicitly checks for the compatibility of the assumed size of int and double among the three components, producing a helpful error message instead of a mysterious crash if you goof.
The VideoToolbox contains up-to-date project documents for current versions of the compilers (names ending in ".µ" for Metrowerks CodeWarrior CW5 and ".π" for THINK C 7 or 8). Users of older versions of the compilers (e.g. THINK C 6 or CW4) unfortunately can't use the new projects: complain to the authors of the compilers, who seem to have no compunction about changing the project format every time they release a new version. I suggest you upgrade to the current version; see "Advice".
All the programs that do accurate luminance control use the monitor-calibration data stored in LuminanceRecord1.h (the number is a screen number, similar--but not identical--to the number that appears in the Monitors control panel). These calibration files describe one of my monitors (an Apple High-Resolution Monochrome), and, naturally, before doing any serious data collection you should create new files that describe your own monitors. Use the CalibrateLuminance program and a photometer.
NUMERICAL RECIPES IN C:
A few programs in the VideoToolbox (CalibrateLuminance.c, PsychometricFit.c, and Quick3) use the (very handy) Numerical Recipes software and book. Required changes to these routines are described in the "Improve Numerical Recipes" document in the Notes folder. I have included pre-compiled CalibrateLuminance and Quick3 applications for users that don't have the Numerical Recipes. The Numerical Recipes C Set for Macintosh (main book, example book, and disk) costs $90 from:
Cambridge University Press
Orders Department
110 Midland Avenue
Port Chester, NY 10573
1-(800)-227-0247
<SANE.h> IS DEAD. LONG LIVE <fp.h>:
In going to the PowerPC, Apple wisely decided to drop <SANE.h>, i.e. their Standard Apple Numerics Environment routines, in favor of <fp.h>, i.e. the Floating-Point C Extensions (FPCE) proposed by the Numerical C Extensions Group (NCEG). SANE was uselessly slow anyway since it was tied to 10-byte doubles, whereas the 68881 floating point chip used 12-byte doubles. The <fp.h> extensions are very welcome, providing some handy math functions and providing standard ways of producing and testing for NAN and INF. <fp.h> provides standard routines very similar to the VideoToolbox routines IsNan and IsFinite. At the moment (November '94), <fp.h> routines are fully implemented only on the PowerPC--only a few are available on 68k--but Apple has promised to fully implement the <fp.h> routines on 68k machines as well. I will continue using my VideoToolbox routines until both PPC and 68k are supported by <fp.h>, then I'll redefine the VideoToolbox routines to just use the <fp.h> routines. If you have any programs that use <SANE.h>, you should think about using <fp.h> instead.
PORTABILITY:
Various issues to do with porting programs among different computers and compilers are discussed in the "Portability" document.
BUGS & SUGGESTIONS:
It's unlikely that you'll find any bugs, but if you do, please send me email so we can fix 'em. Suggestions and code donations (i.e. C routines to be included in the VideoToolbox, possibly in modified form, with full attribution) are warmly appreciated. Also many people have contributed useful paragraphs, which appear in the VideoToolbox notes, with attribution, about specific technical issues that they identified and perhaps solved.
denis@xp.psych.nyu.edu
NOT MULTIFINDER FRIENDLY:
Walt Makous writes, "I ran Sandstorm by clicking on the icon for the application, interrupted it by clicking outside the window, and then resumed it by clicking on the window again. This locks the keyboard so that the only way I can get back control is by using the programmer's switch." REPLY: Alas, I've never had any need to write polite applications that gracefully share the computer with other applications. Experiments always seem to deserve hogging it all. The Sandstorm demo allows you to invoke other applications, because it doesn't obscure the whole window, but it doesn't act like a good citizen in paying attention to the messages it gets from the Finder about what happened. (I would go ahead and make the demos multifinder-friendly if I knew how, but it has seemed worth learning just for the sake of the demos.)
COPYBITS, COPYBITSQUICKLY, and COPYWINDOWS:
CopyBits is one of Apple's more impressive efforts. It's powerful and fast. For my purposes its only drawback is that I haven't always been able to prevent it from doing color translations. So I wrote CopyBitsQuickly to copy images without color translations. (A long time ago CopyBits used to be slow, but that's history. At present CopyBitsQuickly is approximately the same speed as CopyBits.) However, both CopyBits and CopyBitsQuickly require you to supply pixmap pointers, which can be a nuisance. These days, our programs use windows (created by GDOpenWindow) and GWorlds (which are really offscreen windows). Extracting the pixmap's pointer from the guts of the window is straightforward but messy (see BitMapPtr in GDOpenWindow.c). Now you don't have to bother. Just call CopyWindows.c. Its first two arguments are the source and destination windows. The rest of the arguments are like those for CopyBits or CopyBitsQuickly. It makes your programs much easier to write and read, and probably makes them more robust because there are a lot of subtle and fragile assumptions that people often make in calling CopyBits, which CopyWindows takes care of for you. Look at the demo NoiseVBL.c.
BLOCKMOVEDATA:
BlockMoveData is a new (as of System Update 3.0 to System 7.1) variant of BlockMove that omits cache flushing. Calling BlockMoveData() on earlier versions of the operating system will invoke plain old BlockMove(). BlockMove is coded in each computer's ROM to implement the fastest possible move. E.g. it uses the MOVE16 instruction on the 68040 processor. It may be faster than the generic code that most C compilers produce. When the Quadra's were released, Apple added code to the BlockMove trap to flush the instruction cache each time BlockMove was called, just in case the move was copying instructions that were in the cache. However, flushing the cache everytime you call BlockMove sacrifices the speed benefit of the cache, making it less advantageous to call BlockMove. In System Update 3.0 Apple finally gave developers a way of telling BlockMove not to flush the cache. You call BlockMoveData instead. However, if run on computers lacking System Update 3.0 the flag bit distinguishing BlockMoveData from the old BlockMove will be ignored and the cache will be flushed, which will slow you down. BlockMoveData() is defined in Apple's Memory.h in Apple's new Universal Header files, but is not defined in pre-Universal header files. VideoToolbox.h tests for that case and, if necessary, defines BlockMoveData, so that you may use it freely.
68040:
Peter Lennie writes (6/23/93): "On the latest developers CD [June? '93] there's a note about the Quadra's use of a trap to emulate the FINTRZ instruction, which isn't built into the 68040. This instruction is called commonly in the code generated by THINK C [5, when FPU use is enabled], and for me it became an issue in the loops that recalculate lookup tables during chromatic flicker. By rewriting the loop to avoid that instruction (using a small function supplied on the CD) I reduced the time it took to recalculate --as opposed to write-- the tables from 16msec to 1.6 msec." [Does anyone know whether this concern is still applicable to the current version: 7.04? I don't use the Quadra. dgp]
DISCLAIMER (included at the request of the MacPsych archive):
The VideoToolbox is provided "as is" without warranty of any kind. Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, and St. Olaf College make no claims concerning the accuracy or correctness of the computer code contained in, or the results of the use of VideoToolbox. The entire risk as to the results and performance of VideoToolbox is assumed by you. If the VideoToolbox is defective you, and not Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, or St. Olaf College assume the entire cost of all necessary servicing, repair or correction.
